package com.smart.community.region.service;

import java.util.List;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.service.IService;
import com.smart.community.region.dto.BuildingDTO;
import com.smart.community.region.dto.BuildingQueryDTO;
import com.smart.community.region.entity.Building;
import com.smart.community.region.vo.BuildingVO;

/**
 * 楼栋管理服务接口
 * 
 * @author Wu.Liang
 * @since 2024-12-21
 */
public interface IBuildingService extends IService<Building> {

    // ==================== 基础CRUD方法 ====================

    /**
     * 分页查询楼栋列表
     * 
     * @param queryDTO 查询条件
     * @return 分页结果
     */
    IPage<Building> getBuildingPage(BuildingQueryDTO queryDTO) throws Exception;

    /**
     * 获取楼栋详情
     * 
     * @param buildingId 楼栋ID
     * @return 楼栋详情
     */
    Building getBuildingDetail(Long buildingId) throws Exception;

    /**
     * 根据编号查询楼栋
     * 
     * @param buildingNo 楼栋编号
     * @return 楼栋信息
     */
    Building getBuildingByNo(String buildingNo) throws Exception;

    /**
     * 创建楼栋
     * 
     * @param buildingDTO 楼栋信息
     * @return 是否成功
     */
    boolean createBuilding(BuildingDTO buildingDTO) throws Exception;

    /**
     * 更新楼栋
     * 
     * @param buildingDTO 楼栋信息
     * @return 是否成功
     */
    boolean updateBuilding(BuildingDTO buildingDTO) throws Exception;

    /**
     * 删除楼栋
     * 
     * @param buildingId 楼栋ID
     * @return 是否成功
     */
    boolean deleteBuilding(Long buildingId) throws Exception;

    /**
     * 批量删除楼栋
     * 
     * @param buildingIds 楼栋ID列表
     * @return 是否成功
     */
    boolean batchDeleteBuildings(List<Long> buildingIds) throws Exception;

    // ==================== 查询方法 ====================

    /**
     * 根据社区ID查询楼栋列表
     * 
     * @param communityId 社区ID
     * @return 楼栋列表
     */
    List<Building> getBuildingsByCommunity(Long communityId) throws Exception;

    /**
     * 根据社区ID列表查询楼栋树形结构
     * 
     * @param communityIds 社区ID列表
     * @return 楼栋树形结构
     */
    List<Building> getBuildingsTreeByCommunityIds(List<Long> communityIds) throws Exception;

    /**
     * 根据社区ID列表查询楼栋列表
     * 
     * @param communityIds 社区ID列表
     * @param current 当前页码
     * @param size 每页大小
     * @return 楼栋列表
     */
    List<Building> getBuildingsByCommunityIds(List<Long> communityIds, int current, int size) throws Exception;

    // ==================== 状态管理方法 ====================

    /**
     * 更新楼栋状态
     * 
     * @param buildingId 楼栋ID
     * @param status 状态
     * @return 是否成功
     */
    boolean updateBuildingStatus(Long buildingId, Integer status) throws Exception;

    /**
     * 批量更新楼栋状态
     * 
     * @param buildingIds 楼栋ID列表
     * @param status 状态
     * @return 是否成功
     */
    boolean batchUpdateBuildingStatus(List<Long> buildingIds, Integer status) throws Exception;

    // ==================== 统计方法 ====================

    /**
     * 获取楼栋统计信息
     * 
     * @param buildingId 楼栋ID
     * @return 统计信息
     */
    Object getBuildingStats(Long buildingId) throws Exception;

    // ==================== 验证方法 ====================

    /**
     * 检查楼栋编号唯一性
     * 
     * @param buildingNo 楼栋编号
     * @param excludeBuildingId 排除的楼栋ID
     * @return 是否唯一
     */
    boolean checkBuildingNoUnique(String buildingNo, Long excludeBuildingId) throws Exception;

    /**
     * 统计楼栋数量
     * 
     * @param communityId 社区ID（可选）
     * @return 楼栋数量
     */
    Long countBuildings(Long communityId) throws Exception;

    // ==================== 缓存方法 ====================

    /**
     * 清除楼栋缓存
     * 
     * @param buildingId 楼栋ID
     */
    void clearBuildingCache(Long buildingId) throws Exception;

    /**
     * 清除所有楼栋缓存
     */
    void clearAllBuildingCache() throws Exception;

    // ==================== 数据权限业务接口 ====================

    /**
     * 根据社区ID集合获取楼栋ID集合
     * 供其他模块调用，用于数据权限查询
     * 
     * @param communityIds 社区ID集合
     * @return 楼栋ID集合
     */
    List<Long> getBuildingIdsByCommunityIds(List<Long> communityIds) throws Exception;

    /**
     * 根据社区ID获取楼栋ID列表
     * 供其他模块调用，用于数据权限查询
     * 
     * @param communityId 社区ID
     * @return 楼栋ID列表
     */
    List<Long> getBuildingIdsByCommunityId(Long communityId) throws Exception;

    // ==================== VO转换方法 ====================

    /**
     * 转换为VO对象
     * 
     * @param building 楼栋实体
     * @return 楼栋VO
     */
    BuildingVO convertToVO(Building building) throws Exception;

    /**
     * 批量转换为VO对象
     * 
     * @param buildings 楼栋实体列表
     * @return 楼栋VO列表
     */
    List<BuildingVO> convertToVOList(List<Building> buildings) throws Exception;

} 